// Copyright (c) Appeon. All rights reserved.
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. 
// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

namespace SnapObjects.Data
{
    /// <summary>
    ///     Represents an object which is used to build an ORDER BY clause in a SQL statement.
    ///     The ORDER BY clause sorts the data returned by the query.
    /// </summary>
    public interface ISqlOrderBuilder : ISqlBuilder
    {
        /// <summary>
        ///     Creates an ORDER BY clause and specifies one or more sort criteria in ascending order.
        /// </summary>
        /// <param name="orderExpressions">
        ///     (Optional) An array of expressions which specify a column or an expression on which to sort the query result set.
        /// </param>
        /// <returns>
        ///     Returns an ISqlOrderThenBuilder object which can be used to add more sort criteria to the current ORDER BY clause.
        /// </returns>
        ISqlOrderThenBuilder OrderByAscending(params string[] orderExpressions);

        /// <summary>
        ///     Creates an ORDER BY clause and specifies one or more sort criteria in descending order.
        /// </summary>
        /// <param name="orderExpressions">
        ///     (Optional) An array of expressions which specify a column or an expression on which to sort the query result set.
        /// </param>
        /// <returns>
        ///     Returns an ISqlOrderThenBuilder object which can be used to add more sort criteria to the current ORDER BY clause.
        /// </returns>
        ISqlOrderThenBuilder OrderByDescending(params string[] orderExpressions);

        /// <summary>
        ///     Creates an ORDER BY clause and specifies one or more sort criteria using a raw SQL.
        /// </summary>
        /// <param name="orderClause">A string of raw SQL which specifies one or more sort criteria.</param>
        /// <returns>
        ///     Returns an ISqlOrderThenBuilder object which can be used to add more sort criteria to the current ORDER BY clause.
        /// </returns>
        ISqlOrderThenBuilder OrderByRaw(string orderClause);

        /// <summary>
        ///     Creates an ORDER BY clause; and specifies one or more sort criteria using a raw SQL and specifies an alias for the raw SQL.
        /// </summary>
        /// <param name="orderClause">A string of raw SQL which specifies one or more sort criteria.</param>
        /// <param name="alias">The alias for the raw SQL.</param>
        /// <returns>
        ///     Returns an ISqlOrderThenBuilder object which can be used to add more sort criteria to the current ORDER BY clause.
        /// </returns>
        ISqlOrderThenBuilder OrderByRaw(string orderClause, string alias);
    }
}
